Getting started 
=============== 

Installation
------------

To use the mrio toolbox, install it using pip. It is recommended to use a
virtual environment. 

.. code-block:: console

   (.venv) $ pip install mrio-toolbox

You can also clone the latest version from the GitHub repository:

.. code-block:: console

   (.venv) $ git clone https://gitlab.pik-potsdam.de/mrio_toolbox/mrio-toolbox.git 

If you install via git, make sure to update the system path to include the local 
repository. You can do this by adding the following lines to your script:

.. code-block:: python

   import sys
   sys.path.append('/path/to/mrio-toolbox')

before you import the library to your script as follows:

.. code-block:: python

   from mrio_toolbox import MRIO, Part


Contents of the library
-----------------------

Core functions
~~~~~~~~~~~~~~

The MRIO class is the centerpiece of the library. 
Each MRIO object holds a collection of parts, which themselves represent different aspects of the table, 
for example the inter-industry matrix, the final demand matrix, the value added etc. 

- The MRIO class provides methods to manipulate all parts, e.g. to load new parts, update groupings, aggregate data etc 
- The Parts class provides methods to manipulate individual parts, e.g. to sum along different axes, select a partition, compute a leontief inverse etc.

Utilities
~~~~~~~~~

The library has additional utilities: 

- Extractor functions to read in raw MRIO tables from various providers. 
- Saver functions to save MRIO objects to .nc files
- Loader functions to load MRIO objects from .npy, .csv, .excel or .nc files
- A multi-scale mapping algorithm to map PRIMAP emission data into MRIO tables. 

For a detailled description of the classes and their methods see the `API reference <autoapi/index.html>`_. or the :doc:`Example use` section.


Read in data tables
-------------------
The toolbox has extractor functions that support the the following MRIO tables: 

- Eora26
- Exiobase3
- Figaro
- Gloria
- GTAP11
- ICIO
- WIOD

There is an automatic downloader for the Figaro database from Eurostat, see the `example notebook`_ 

.. _example notebook: example_figaro.nblink

For the other tables, please download the data manually from the respective websites and run the extractor 
function to safe the data in the netCDF format used by the toolbox.

For example, to extract the Eora26 table of the year 2015, use the following code:

.. code-block:: python
   
   import os
   from mrio_toolbox import MRIO, extract_MRIO

   source_path = "/path/to/downloaded/eora26/files"
   destination_path = "/path/to/save/formatted/eora26/files"

   extract_MRIO(
      table="eora26",
      year = "2015",
      source= source_path,
      destination= destination_path
   )
   
   file_path = os.path.join(destination_path, f"eora26_year2015.nc")
   mrio = MRIO(file = file_path)

Note that if we provide a destination keyword, the extractor function saves the formatted files with 
the naming convention `{table}_year{year}.nc` in the specified destination folder.